Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@app/api/content-agent/`[platform]/route.ts:
- Around line 15-59: Add automated tests for the webhook route to cover the GET
404 path, POST Slack URL-verification short-circuit, and normal dispatch via
contentAgentBot.webhooks: write unit tests that invoke the exported GET and POST
handlers (mocking the params promise to return { platform }), stub
contentAgentBot.webhooks to include a fake handler and assert it is called and
its Response returned, stub contentAgentBot.initialize to avoid startup
side-effects, stub handleUrlVerification to return a Response for the Slack
short-circuit case and assert that initialize and the webhook handler are not
called, and add a test where no handler exists to assert a 404 Response; also
verify the waitUntil callback is accepted by your fake handler to exercise the
after(() => p) path.

In `@app/api/launch/route.ts`:
- Around line 45-51: Add unit/integration tests that cover the new API route's
success and failure paths by exercising POST which calls
generateCampaignHandler: create tests for (1) successful stream response (mock
request body and any downstream services, assert streaming chunks and 200), (2)
auth failures (simulate missing/invalid auth and assert the expected 401/403
response), and (3) invalid JSON/body validation errors (send malformed/invalid
payloads and assert 400 and proper error payload). Mock or stub any external
dependencies used by generateCampaignHandler (auth middleware, validators, and
downstream APIs) so tests are deterministic, and include assertions on status
codes and response body/stream behavior for each case.

In `@lib/content-agent/bot.ts`:
- Around line 21-25: The redis.connect() call in createContentAgentBot() is
being fired-and-forgotten; await the connection so callers get a connected
client (or surface connection errors) before the state adapter is created.
Modify createContentAgentBot() (or add an async initialize() method used by
callers like the GET handler) to await redis.connect() when redis.status ===
"wait", propagate any thrown error instead of catching it in a detached promise,
and only construct the state adapter after the successful await; ensure callers
(including code that currently uses the bot directly) await the
factory/initialize promise so the bot is never used with an unconnected Redis
client.

In `@lib/content-agent/handleContentAgentCallback.ts`:
- Around line 44-61: The branch in handleContentAgentCallback that posts
"Content generation finished but no videos were produced." hides per-run
failures and timeouts; instead, when videos.length === 0 use the
already-computed failed array (and any timeout/other non-completed statuses from
validated.results) to build a detailed message: list each failed run (include
status, error/captionText/videoUrl if present) and the count of
failures/timeouts, and then post that constructed message via thread.post rather
than the generic string so callers can see which runs failed and why (refer to
variables validated.results, videos, failed and the thread.post call to locate
where to make the change).

In `@lib/content-agent/handlers/handleContentAgentMention.ts`:
- Around line 111-140: The code uses Promise.allSettled over
triggerCreateContent but keeps the original batch value when calling
thread.setState and triggerPollContentRun, which misreports runs if some
promises failed; change the logic to inspect the allSettled results, compute
successful runIds (as already done), and if runIds.length === 0 throw or return
an error (already handled), but if some succeeded and some failed either (a)
update the saved batch count to runIds.length before calling thread.setState and
then call triggerPollContentRun with those runIds, or (b) treat any failure as
fatal and bail out so no partially-started batch is recorded; implement the
chosen approach by modifying the block around Promise.allSettled / runIds /
thread.setState / triggerPollContentRun to use the adjusted batch/runIds values
and avoid telling users to retry when some runs are already live.

In `@lib/credits/handleChatCredits.ts`:
- Around line 14-20: The JSDoc for the function in
lib/credits/handleChatCredits.ts incorrectly uses nested param names like
`@param usage.usage`, `@param usage.model`, and `@param usage.accountId`; update
the comment to document the actual top-level parameters from the function
signature (e.g., `@param usage - The language model usage data`, `@param model -
The model ID used for the chat`, `@param accountId - The account ID to deduct
credits from (optional)`), remove the redundant `@param usage` line and any
dot‑notation entries, and ensure the JSDoc parameter names match the
destructured parameters used by the function (look for the function
name/identifier in this file to locate the signature).

In `@lib/launch/buildCampaignPrompt.ts`:
- Around line 8-25: This module currently exports multiple prompt builders
(buildCampaignSystemPrompt and buildCampaignUserPrompt); split them so each file
exports exactly one function: move either buildCampaignSystemPrompt or
buildCampaignUserPrompt into a new file (e.g., create
buildCampaignSystemPrompt.ts or buildCampaignUserPrompt.ts), keep the other in
the original file, update any imports/exports to reference the new filename, and
ensure both functions are exported as default or named per project convention
and all callers (tests/consumers) import the correct symbol name; run
type-checks and tests to confirm no import paths remain broken.
- Around line 26-35: The prompt interpolates raw user fields (artist_name,
song_name, genre, release_date, description) into a marker-sensitive template
and is vulnerable to marker injection; add a small sanitizer function (e.g.
sanitizePromptField) and call it for each symbol before building the string in
buildCampaignPrompt: the sanitizer should strip or normalize newlines to spaces,
remove or escape common section/marker tokens (e.g. lines that begin with
hashes, repeated dashes/equals, or labels like "Artist:", "Song/Release:"), trim
and optionally enforce a max length, then use the sanitized values in the
returned template to prevent downstream parsing breaks.

In `@lib/launch/generateCampaignHandler.ts`:
- Around line 22-35: Wrap the call to request.json() in a try-catch and return a
controlled JSON error response with getCorsHeaders() if parsing fails, and
likewise wrap the streamText(...) invocation (the call that uses DEFAULT_MODEL,
buildCampaignSystemPrompt(), buildCampaignUserPrompt(validated)) in its own
try-catch to catch generation errors and return a consistent NextResponse.json
error with CORS headers; keep the existing validateLaunchBody flow (checking for
NextResponse) and only call streamText after validated succeeds, and ensure any
caught error messages are included in the JSON error body so handlers like
getAccountHandler/createCatalogSongsHandler style are followed.

---

Outside diff comments:
In `@app/api/transcribe/route.ts`:
- Around line 12-33: Stop reading account_id from the request body and derive
the account ID via validateAuthContext(); remove the body.account_id usage and
instead call validateAuthContext() in this route, extract the authenticated
account id and pass that as ownerAccountId to processAudioTranscription (instead
of account_id). Also perform Zod validation on the incoming body fields
(audio_url, artist_account_id, title, include_timestamps) before calling
processAudioTranscription so malformed input is rejected early; ensure
artist_account_id still comes from the validated body and that the validated
include_timestamps is forwarded to includeTimestamps.

---

Minor comments:
In `@app/api/accounts/`[id]/route.ts:
- Around line 26-27: Remove the redundant JSDoc tag "@param params.params" from
the route handler's comment and keep a single clear "@param params" entry
describing the route params (account ID); update the JSDoc above the exported
route handler (the function in app/api/accounts/[id]/route.ts that destructures
params) so it only documents "params" (or "params.id" in the description) and
remove the misleading duplicate entry.

In `@app/api/admins/privy/route.ts`:
- Around line 18-20: Replace the empty JSDoc block above the OPTIONS handler
with a concise summary that documents this endpoint as the CORS preflight
response for the Privy admin route and states it returns HTTP 204 No Content;
update the JSDoc placed immediately above the OPTIONS function/handler (the
block currently empty above the OPTIONS declaration) to include a one-line
description like "CORS preflight response — returns 204 No Content" and mention
it handles preflight checks for allowed methods and headers.

In `@app/api/coding-agent/`[platform]/route.ts:
- Around line 38-40: Remove the incorrect JSDoc param entry "@param
params.params" from the POST route JSDoc and leave only the correct "@param
params" to match the actual handler signature; update the JSDoc block above the
exported POST function (route handler) in
app/api/coding-agent/[platform]/route.ts so it contains a single "@param params"
line describing the route params.
- Around line 13-15: Remove the incorrect JSDoc entry "@param params.params"
from the GET route's documentation; update the JSDoc for the GET handler (the
exported GET function in route.ts) to only document the real parameter (e.g.,
"@param params - Route params containing the platform name") and any other valid
params, ensuring there are no nested or duplicate param lines like
"params.params" that don't exist on the function signature.

In `@lib/coding-agent/handleMergeSuccess.ts`:
- Around line 10-11: The JSDoc for handleMergeSuccess has an incomplete `@param`
entry — update the comment above the handleMergeSuccess function to document the
state parameter by name and a short description of what it represents (e.g.,
"state - current agent state object containing merge context, branch info, and
any relevant metadata"), ensuring the `@param` line follows JSDoc format and
accurately reflects the shape/purpose of the state argument used in
handleMergeSuccess.

In `@lib/content-agent/getThread.ts`:
- Around line 10-11: The threadId parsing in getThread.ts that derives
adapterName and channelId from threadId.split(":") is fragile; update the logic
that computes adapterName and channelId to first validate threadId has at least
two colon-separated parts (e.g., parts = threadId.split(":") and parts.length >=
2), handle cases with extra parts (for formats like "slack:channelId:threadTs")
by using parts[0] and parts[1] to build channelId, and if validation fails
return a safe failure (throw a descriptive error or return null) and/or log the
invalid threadId instead of producing "undefined" in channelId. Ensure
references are to the existing adapterName and channelId variables in
getThread.ts so the change is localized.

In `@lib/content/createContentHandler.ts`:
- Around line 12-13: Update the JSDoc for the createContentHandler function by
adding a brief description to the existing `@param` request tag explaining what
the `request` parameter represents (e.g., the incoming HTTP request or payload
object, its expected shape or purpose) so the comment clearly documents the
input to createContentHandler; keep the description concise and mention any
important fields or types if applicable.

In `@lib/flamingo/getFlamingoPresetsHandler.ts`:
- Line 13: Update the JSDoc for the getFlamingoPresetsHandler function by
replacing the bare "@param request" tag with a concise description of what the
request argument represents (e.g., the incoming HTTP request object containing
query/body headers used to determine which Flamingo presets to return), keeping
the parameter name "request" so it matches the function signature; ensure the
JSDoc clearly states the expected shape or purpose of the request (for example
that it is the incoming API request used to read query params or body payload to
filter presets).

In `@lib/github/expandSubmoduleEntries.ts`:
- Around line 14-22: The JSDoc incorrectly nests parameters under
regularEntries; update the comment for the function (expandSubmoduleEntries) by
removing `@param` regularEntries.regularEntries, `@param`
regularEntries.submoduleEntries, and `@param` regularEntries.repo (and its nested
owner/repo/branch lines), and instead declare top-level params: `@param`
regularEntries, `@param` submoduleEntries, and `@param` repo, plus explicit `@param`
repo.owner, `@param` repo.repo, and `@param` repo.branch entries so the destructured
repo fields are documented correctly.

In `@lib/github/getRepoGitModules.ts`:
- Around line 7-12: The JSDoc for getRepoGitModules contains invalid nested
`@param` entries (e.g., `@param` owner.owner, `@param` owner.repo, `@param`
owner.branch) that contradict the function signature which takes owner, repo,
and branch as direct string parameters; remove those nested tags and ensure only
top-level `@param` tags remain for owner, repo, and branch (and adjust any
descriptions if needed) so the documentation matches the actual
getRepoGitModules parameter list.

In `@lib/github/resolveSubmodulePath.ts`:
- Around line 9-12: Remove the invalid nested JSDoc param entries that reference
githubRepo.githubRepo and githubRepo.path and instead document the actual
destructured parameters used by the function (githubRepo and path); update the
JSDoc to contain only two `@param` tags (e.g., `@param` githubRepo - The parent
GitHub repository URL and `@param` path - The file path to resolve) so the
comments match the resolveSubmodulePath function signature.

In `@lib/prompts/getSystemPrompt.ts`:
- Line 16: The JSDoc for params.orgId is missing a description; update the JSDoc
block in getSystemPrompt.ts (the getSystemPrompt function's comment) to provide
a clear description for params.orgId (e.g., "The ID of the organization" or
similar), matching the style of the other parameter descriptions so the
documentation is consistent and complete.

In `@lib/slack/getSlackUserInfo.ts`:
- Around line 19-21: Add missing JSDoc descriptions for the parameters of
getSlackUserInfo: document what the token parameter is (e.g., Slack OAuth or bot
token used to authenticate API requests) and what the userId parameter
represents (the Slack user ID whose profile/info will be retrieved), and include
expected types and any important format or usage notes so the `@param` tags are
complete and informative.

---

Nitpick comments:
In `@app/api/transcribe/route.ts`:
- Around line 5-8: Replace the placeholder JSDoc above the route handler
(exported POST(req) function) with a concise, descriptive comment that
summarizes the route purpose, expected request body shape, response shape, and
possible errors: e.g., state that POST accepts either multipart/form-data with a
"file" field (audio) or JSON with an "audio" base64 string and optional
"language" string, returns 200 with a JSON body { transcription: string } on
success, and returns 400 for invalid input or 500 for server/transcription
errors; include `@param` req, `@returns`, and `@throws/`@errors tags and a one-line
summary so the JSDoc sits immediately above the POST(req) export.

In `@lib/admins/privy/countNewAccounts.ts`:
- Around line 8-10: Update the JSDoc for the countNewAccounts function by adding
concise descriptions to the `@param` tags: describe what the users parameter
represents (e.g., array of User objects or user count input) and what the period
parameter represents (e.g., time window format like '7d' or start/end Date), so
the comment above countNewAccounts clearly documents the expected types and
semantics of users and period.

In `@lib/admins/privy/fetchPrivyLogins.ts`:
- Around line 23-26: The JSDoc for fetchPrivyLogins is non-informative (only
lists "@param period" with no description); update the JSDoc for the function
fetchPrivyLogins to either remove the block entirely or replace it with a short
summary of what the function does and a clear description of the "period"
parameter (expected type/format/units and effects), and document the return
value if applicable (e.g., what shape or errors) so the comment is meaningful.

In `@lib/admins/privy/getCutoffMs.ts`:
- Around line 8-9: The JSDoc for getCutoffMs is missing a description for the
`@param` period tag; update the comment above the getCutoffMs function to add a
concise description for period (what it represents, allowed values or enum
names, and units if applicable, e.g., "period — time window name
('day'|'week'|'month') used to compute cutoff in milliseconds"), so readers know
how to call getCutoffMs and what each period value means.

In `@lib/admins/privy/getLatestVerifiedAt.ts`:
- Around line 7-8: Add a short descriptive text to the JSDoc `@param` user tag for
the getLatestVerifiedAt function: specify what the `user` parameter represents
(e.g., "the user object or record to inspect" or "User model instance whose
verification timestamps will be checked"), include expected shape/type if known
(e.g., contains verifiedAt or verification history), and any important
preconditions the function requires from `user`.

In `@lib/admins/privy/toMs.ts`:
- Around line 4-5: Update the JSDoc for the toMs function so the `@param`
timestamp tag includes a clear description of expected units and format (e.g.,
"Timestamp in seconds or milliseconds; if in seconds, will be converted to
milliseconds"), referencing the toMs function name so maintainers know which
docblock to edit.

In `@lib/admins/slack/extractGithubPrUrls.ts`:
- Around line 28-30: The JSDoc for extractGithubPrUrls is missing short
descriptions for its parameters; update the comment block above the
extractGithubPrUrls function to add brief `@param` entries for text, attachments,
and blocks (e.g., what type/value each represents and how it’s used) so
IDE/tooltips show actionable info; keep each description one short sentence
mentioning expected type/role (e.g., "text: raw Slack message text to scan for
PR URLs"), and ensure the parameter names exactly match the function signature.

In `@lib/admins/slack/fetchThreadPullRequests.ts`:
- Around line 21-24: Update the JSDoc for fetchThreadPullRequests to include
one-line descriptions for each `@param`: describe token (bot token or OAuth token
used for Slack API calls), channel (Slack channel ID where the thread resides),
and threadTs (parent thread timestamp/ts of the thread); place these short
clarifications on the existing `@param` lines in
lib/admins/slack/fetchThreadPullRequests.ts so tooling and future readers
immediately understand each parameter's purpose.

In `@lib/ai/isEmbedModel.ts`:
- Line 7: Update the JSDoc for the isEmbedModel function by adding a short
description to the existing `@param` m tag (e.g., "Gateway model entry to
evaluate") so the parameter is documented; locate the JSDoc above the
isEmbedModel function and replace the bare "@param m" with "@param m - Gateway
model entry to evaluate" (or equivalent concise wording) to make the annotation
actionable for readers and tooling.

In `@lib/catalog/formatCatalogSongsAsCSV.ts`:
- Around line 5-6: Update the JSDoc for the formatCatalogSongsAsCSV function to
include a descriptive `@param` for songs: explain that songs is the array of song
objects (or the expected shape, e.g., objects containing title, artist, album,
duration, etc.) that will be formatted into CSV; ensure the description clearly
states the parameter type and purpose so IDE tooltips and generated docs display
meaningful information.

In `@lib/catalog/getCatalogDataAsCSV.ts`:
- Around line 6-7: The JSDoc for the getCatalogDataAsCSV function has an
incomplete `@param`; update the comment for the `@param` catalogId in the
getCatalogDataAsCSV JSDoc to describe what the parameter represents (e.g.,
"catalogId - the unique identifier of the catalog to export, typically a string
ID or UUID") so callers understand the expected value and purpose.

In `@lib/catalog/getCatalogSongs.ts`:
- Around line 28-34: The JSDoc for getCatalogSongs is too sparse—update the
comment block above the getCatalogSongs function to document each parameter
(catalogId: string — catalog identifier, pageSize: number — max items per page,
include valid range or default, page: number — 0-based or 1-based index and
default, artistName?: string — optional filter) and add an `@returns` describing
the returned Promise shape (e.g., paginated list of songs and metadata or error
conditions). Keep descriptions short, mention any constraints/defaults, and
ensure the param names exactly match the function signature (catalogId,
pageSize, page, artistName) and include `@returns` with the return type summary.

In `@lib/chats/processCompactChatRequest.ts`:
- Around line 20-22: Update the JSDoc for the processCompactChatRequest function
to add clear descriptions for the nested params keys (params.chatId,
params.prompt, params.accountId): state what each field represents, expected
type/format, whether it is required or optional, and any constraints (e.g.,
chatId is a UUID or string identifier, prompt is the user message text,
accountId is the tenant/user account identifier). Edit the comment block above
the processCompactChatRequest function (the `@param` params entry and its nested
`@param` params.* lines) to include these concise descriptions so callers and
maintainers understand intent and format.

In `@lib/content-agent/getThread.ts`:
- Around line 9-16: Duplicate thread reconstruction logic in getThread is
implemented in ContentAgent's getThread (using ThreadImpl and
ContentAgentThreadState) and in CodingAgent's getThread; extract a single
generic utility function getThread<TState>(threadId: string) that parses
adapterName and channelId and returns new ThreadImpl<TState>({ adapterName, id:
threadId, channelId }), place it in a shared module and update both existing
getThread implementations to import and call this generic getThread with their
specific state types (e.g., getThread<ContentAgentThreadState> and
getThread<CodingAgentThreadState>) so ThreadImpl usage and parsing logic are
centralized.

In `@lib/content-agent/handlers/registerHandlers.ts`:
- Around line 9-10: The module currently calls
registerOnNewMention(contentAgentBot) and
registerOnSubscribedMessage(contentAgentBot) at import time which causes side
effects; change this to export an explicit initialization function (e.g.,
initRegisterHandlers or registerContentAgentHandlers) that performs these calls
instead, and add an internal idempotency guard (a module-level boolean like
"registered") so repeated calls are safe; update callers/tests to invoke the new
init function during startup or test setup rather than relying on module import
side-effects, ensuring registerOnNewMention, registerOnSubscribedMessage, and
contentAgentBot are referenced inside the init function only.

In `@lib/content/contentTemplates.ts`:
- Around line 28-31: Update the JSDoc for the function in contentTemplates.ts to
include a short description of the function and a descriptive `@param` for
template that states the expected format/source (e.g., "template: string |
TemplateObject - the HTML/text template or template identifier used to render
content; may include placeholders like {{name}} and should come from the
templates directory or template service"), so developers know what type/value
and origin are expected; update any additional tags (returns, throws) if
applicable to match the implementation.

In `@lib/content/createContentHandler.ts`:
- Around line 15-87: The createContentHandler function is overlong and mixes
responsibilities; extract the GitHub repo resolution, payload construction, and
batch trigger logic into helpers to reduce size and improve testability:
implement resolveGithubRepo(params: {accountId, artistAccountId, artistSlug})
that uses getArtistContentReadiness and falls back to selectAccountSnapshots
(throwing a clear error if none), implement buildContentPayload(validated,
githubRepo) to create the payload object, and implement
executeBatchTriggers(payload, count) that calls triggerCreateContent via
Promise.allSettled and returns { runIds, failedCount }; then refactor
createContentHandler to call these helpers and keep only orchestration, error
handling, and response formatting (using the same response shape).

In `@lib/content/getArtistContentReadiness.ts`:
- Around line 25-29: The JSDoc uses an auto-generated parameter name `root0`
which is unclear; update the docblock for the function getArtistContentReadiness
to use a meaningful parameter name such as `options` (or `params`) and rename
all related JSDoc tags from `@param root0.accountId`, `@param
root0.artistAccountId`, `@param root0.artistSlug` to `@param options.accountId`,
`@param options.artistAccountId`, `@param options.artistSlug` so the docs
clearly match the function signature and intent.

In `@lib/content/validateCreateContentBody.ts`:
- Around line 43-44: Update the JSDoc for the validateCreateContentBody
function: add a descriptive `@param` for the request argument (include expected
type/shape, e.g., Request or a specific DTO and what fields are required) and
add a `@returns` tag describing the return type and possible values (e.g., boolean
or an object with validation errors). Ensure the JSDoc sits immediately above
the validateCreateContentBody declaration so IDEs pick up the types and
descriptions.

In `@lib/mcp/resolveAccountId.ts`:
- Around line 19-20: Update the JSDoc for resolveAccountId to provide clear
descriptions for the params object properties: document what params.authInfo
contains (e.g., authentication context/token, the fields used such as userId,
tenantId, or permissions) and how it is used by resolveAccountId, and describe
params.accountIdOverride (e.g., an optional account ID that, when present, takes
precedence over values derived from authInfo or defaults). Mention expected
types and whether the fields are optional/required and any validation/format
expectations so future readers understand purpose and constraints.

In `@lib/mcp/tools/transcribe/registerTranscribeAudioTool.ts`:
- Around line 18-21: Add a meaningful JSDoc for the registerTranscribeAudioTool
function: describe what the function does (registers the "transcribe_audio" tool
on the provided server), document the server parameter (type and role, e.g.,
Express or Hapi server instance used to attach routes/handlers), mention side
effects (mutates server by registering routes/tools), and include a `@returns` tag
(void or Promise<void> as appropriate) and any thrown errors; reference
registerTranscribeAudioTool, its server parameter, and the registered
"transcribe_audio" tool in the comment.

In `@lib/slack/getBotChannels.ts`:
- Line 13: Update the JSDoc for the token parameter in getBotChannels to a
concise, descriptive phrase (for example "Slack bot OAuth token") so generated
docs are clear; edit the `@param` token line in the JSDoc block above the
getBotChannels function to replace the vague token comment with the short
description mentioning it's the Slack bot OAuth token used for API calls.

In `@lib/slack/getBotUserId.ts`:
- Around line 11-12: Update the JSDoc for the token parameter in getBotUserId
(in lib/slack/getBotUserId.ts) to clearly state it is the Slack bot OAuth token
used for the auth.test call (e.g., "Slack bot OAuth token used for auth.test to
retrieve the calling bot's user ID"), so future callers know exactly what to
pass; keep the description simple and unambiguous and ensure the `@param` name
matches the function parameter name.

In `@lib/slack/getSlackUserInfo.ts`:
- Around line 23-25: The parameter name userId in getSlackUserInfo conflicts
with our repo-wide "account" terminology but is acceptable at this external-API
boundary; keep the parameter as userId to match Slack's users.info API and add a
short comment above getSlackUserInfo explaining this naming decision (e.g.,
"uses Slack 'user' terminology to match Slack API; internal code should map to
'account' after this boundary") so future readers understand the trade-off and
where mapping to 'account' should occur.

In `@lib/supabase/account_artist_ids/getAccountArtistIds.ts`:
- Around line 11-13: Update the JSDoc for the getAccountArtistIds function: add
clear descriptions for the top-level params object and its nested properties by
documenting params.artistIds and params.accountIds (e.g., "artistIds - optional
array of artist ID strings to filter results" and "accountIds - optional array
of account ID strings to filter results"), indicate whether each is optional,
the expected type, and how they affect function behavior (used as filters), and
keep the param names exactly as in the signature (params, params.artistIds,
params.accountIds) so IDEs and docs pick up the details.
- Around line 44-47: The getAccountArtistIds function currently logs errors and
returns an empty array which hides failures; change its error handling so it
doesn't swallow errors: either throw the original error (preferred for library
functions) from getAccountArtistIds after logging the detailed error, or modify
its return type to a result object (e.g., { data: string[] | null, error: Error
| null }) and return the error instead of an empty array; ensure you update any
callers of getAccountArtistIds to handle the thrown error or the new result
object accordingly and keep the processLogger/console message including the full
error details.

In `@lib/supabase/song_artists/insertSongArtists.ts`:
- Around line 8-10: Add a one-line description to the existing JSDoc `@param` tag
for songArtists in insertSongArtists (the function that upserts song-artist
relationships) explaining the expected shape and intent, e.g., "Array of
song-artist join rows to upsert (each object should contain song_id and
artist_id and optional metadata)"; update the JSDoc above the insertSongArtists
function so it follows the project's documented JSDoc pattern for
lib/supabase/**/*.ts files.

In `@lib/supabase/storage/uploadFileByKey.ts`:
- Around line 7-11: Update the JSDoc for the uploadFileByKey function to add
brief descriptions for each parameter: describe "key" as the storage object
path, "file" as the Blob/File or stream to upload, and "options" as an optional
object; explicitly document options.contentType (default: inferred from the file
or fallback to "application/octet-stream") and options.upsert (default: false,
meaning fail if object exists). Also ensure the module follows the Supabase
pattern by importing the Supabase client from "@/lib/supabase/serverClient" and
that uploadFileByKey's JSDoc includes return type and notes about thrown errors
so callers see expected return and error behavior.

In `@lib/transcribe/processAudioTranscription.ts`:
- Around line 69-72: Update the sparse JSDoc for the function handling audio
transcription (processAudioTranscription) to document expected contentType
values (e.g., "audio/mpeg", "audio/mp3", "audio/wav", "audio/x-m4a" or common
file extension equivalents) and specify fallback behavior: when contentType is
missing or unrecognized the function will treat the input as "mp3". Add a short
summary line describing the function purpose and extend the `@param` contentType
description to list accepted MIME types/variants and explicitly state the
default/fallback of "mp3".
- Around line 10-12: The JSDoc for the params argument in
processAudioTranscription is a placeholder; update the docblock for the
processAudioTranscription function to either remove the empty "@param params"
tag or replace it with a one-line description of the expected keys (e.g.,
audioBuffer/audioPath, language, model, options callback fields) and their
types/optional status so callers know what to pass; reference the params
parameter in the processAudioTranscription function signature and include
concise descriptions for each expected key.

In `@lib/transcribe/saveAudioToFiles.ts`:
- Around line 5-8: The JSDoc above the saveAudioToFiles function is empty;
either flesh it out or remove it. Locate the saveAudioToFiles function in
saveAudioToFiles.ts and either add a proper JSDoc describing the function, each
param (types/purpose) and return value, or delete the empty /** ... */ block so
TypeScript types are relied upon instead.

In `@lib/transcribe/saveTranscriptToFiles.ts`:
- Around line 5-8: The JSDoc above the function is empty and should be completed
or removed; update the JSDoc for the saveTranscriptToFiles function to include a
brief one-line description and a clear `@param` description for the params object
(and document key properties if any), or simply delete the entire /** ... */
block if the TypeScript signature is sufficient, ensuring you reference the same
params identifier used by saveTranscriptToFiles.

In `@lib/transcribe/types.ts`:
- Around line 59-60: Update the JSDoc block in lib/transcribe/types.ts to add a
clear description for the `@param` error tag: state what shape or types of errors
are expected (e.g., Error, string, null/undefined, or a custom
TranscriptionError), whether it can be optional, and how callers should
interpret its fields (message, code, or nested details). Locate the JSDoc that
contains "@param error" and expand the tag to a short sentence describing the
expected error types and any important properties or optionality so the
transcribe-related types and functions can be properly documented.

In `@lib/trigger/triggerPollContentRun.ts`:
- Around line 3-6: The type PollContentRunPayload is declared but not exported,
which prevents reuse across the content agent flow; export PollContentRunPayload
from triggerPollContentRun.ts so other modules (e.g., the poll-content-run task
definition or consumers) can import it for type-safe integration, ensuring the
declaration (type PollContentRunPayload = { runIds: string[]; callbackThreadId:
string; }) is exported.